Add FromJSON instance for new experimental TxOut by Jimbo4350 · Pull Request #1179 · IntersectMBO/cardano-api

Jimbo4350 · 2026-04-09T15:56:40Z

Context

Implements FromJSON instances for the new TxOut era type (which wraps L.TxOut era) in the experimental API, matching the JSON format produced by the ToJSON instances added in #1176.

Closes #926

Changelog

- description: |
    Add FromJSON instance for new experimental TxOut type with per-era
    concrete instances, inline datum parsing from inlineDatumRaw with
    hash validation, and reference script support via scriptInAnyLangToLedgerScript
  type:
   - feature
  projects:
   - cardano-api

How to trust this PR

Concrete FromJSON instances for each era (Shelley through Conway), mirroring the ToJSON structure from Add ToJSON instance for new experimental TxOut #1176
Pre-Alonzo eras parse address and value only via shared txOutBaseParseJson helper
Alonzo adds datum hash parsing via dataHashTxOutL
Babbage+ adds inline datum parsing from inlineDatumRaw (hex-encoded original CBOR bytes) with hash validation against inlineDatumhash, and reference script parsing via scriptInAnyLangToLedgerScript
Supplemental datums deliberately unsupported — the ledger TxOut does not carry them
Helper functions: addrFromJson (reverse of addrToJson), scriptInAnyLangToLedgerScript (reverse of ledgerScriptToScriptInAnyLang)
Property test verifies JSON round-trip (fromJSON . toJSON = id) across all Shelley-based eras

Checklist

Commit sequence is logical and each commit has a good commit message
New tests are added if needed and old tests still pass
Code is formatted with fourmolu
Self-reviewed the diff

github-actions · 2026-06-12T02:24:03Z

This PR is stale because it has been open 45 days with no activity.

Add per-era FromJSON instances for the experimental TxOut type, mirroring the ToJSON structure. Pre-Alonzo eras parse address and value only; Alonzo adds datum hash support; Babbage+ adds inline datum (parsed from inlineDatumRaw with hash validation) and reference script support. Supplemental datums are deliberately unsupported as the ledger TxOut does not carry them.

Copilot

Pull request overview

This PR adds FromJSON support for the experimental TxOut era wrapper (around L.TxOut era), intended to be the inverse of the ToJSON format introduced in #1176, and adds a property test to verify JSON round-tripping for supported Shelley-based eras.

Changes:

Implement FromJSON instances for experimental TxOut across Shelley→Conway, including Babbage+ inline datum parsing (from inlineDatumRaw) with hash validation and reference script support.
Refactor datum/reference-script JSON field emission to a shared helper (datumAndRefScriptFields).
Add a Hedgehog property test for encode/eitherDecode round-tripping, plus a Herald changelog fragment.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
cardano-api/test/cardano-api-test/Test/Cardano/Api/Json.hs	Adds a JSON round-trip property for the new experimental `TxOut` (with Dijkstra currently skipped).
cardano-api/src/Cardano/Api/Experimental/Tx/Internal/BodyContent/New.hs	Adds `FromJSON` parsing for experimental `TxOut` (base fields, datum hash, inline datum raw+hash validation, reference scripts).
.changes/20260420_cardano_api_fromjson_experimental_txout.yml	Adds the required changelog fragment documenting the new feature.

+-- | Verify that the new experimental 'TxOut' round-trips through JSON
+-- (encode then decode) for all Shelley-based eras.
+prop_new_txout_json_roundtrip :: Property


+    Nothing -> case mDatumHash of
+      Just dh -> pure $ L.DatumHash dh
+      Nothing -> pure L.NoDatum


palas

Looks good. I just made a couple of small suggestions.

inlineDatumhash is really weird, both the capitalisation and it being omitted on Babbage when it inline datum is not present (instad of just being null). But it is outside of the scope of the PR

carbolymer

I think usage of cast is imprecise here and will be an annoyance down the road. I think we should stop for a moment and decide how we would like to support legacy eras using experimental API.

Moreover, PR has a lot of duplication from pattern matching on Maybe and Either.

carbolymer · 2026-06-26T12:05:30Z

+  Add FromJSON instances for the new experimental TxOut type, matching
+  the JSON format produced by the corresponding ToJSON instances. Inline
+  datums are parsed from inlineDatumRaw with hash validation against
+  inlineDatumhash. Reference scripts are parsed via the existing
+  FromJSON ScriptInAnyLang instance and converted to ledger scripts.
+  Supplemental datums are deliberately unsupported since the ledger
+  TxOut does not carry them.


redundant line wraps - they will leak into the final changelog

carbolymer · 2026-06-26T12:52:44Z

+      rawBytes <- case Base16.decode (Text.encodeUtf8 rawHex) of
+        Left err -> fail $ "babbageOnwardsTxOutParseJson: failed to hex-decode inlineDatumRaw: " <> show err
+        Right bs -> pure bs


The explicit case matching on Maybe and Either repeats itself too many times in this PR. I think this warrants creating helper functions to make the code more readable.

We have failEitherWith for example:

Suggested change

rawBytes <- case Base16.decode (Text.encodeUtf8 rawHex) of

Left err -> fail $ "babbageOnwardsTxOutParseJson: failed to hex-decode inlineDatumRaw: " <> show err

Right bs -> pure bs

rawBytes <- failEitherWith (("babbageOnwardsTxOutParseJson: failed to hex-decode inlineDatumRaw: " <>) . show) $

Base16.decode (Text.encodeUtf8 rawHex)

carbolymer · 2026-06-26T12:55:28Z

+  refScript <- case mRefScript of
+    Nothing -> pure SNothing
+    Just script -> SJust <$> scriptInAnyLangToLedgerScript script


Suggested change

refScript <- case mRefScript of

Nothing -> pure SNothing

Just script -> SJust <$> scriptInAnyLangToLedgerScript script

refScript <- fmap maybeToStrictMaybe $ forM mRefScript scriptInAnyLangToLedgerScript

carbolymer · 2026-06-26T12:57:18Z

+      & L.datumTxOutL .~ datum
+      & L.referenceScriptTxOutL .~ refScript
+
+-- | Convert a 'ScriptInAnyLang' to a ledger 'L.Script'. Reverse of 'ledgerScriptToScriptInAnyLang'.


This function should be placed near its reverse.

Replace the three separate where-bound helpers (datumFields, inlineDatumFields, refScriptFields) with a single top-level datumAndRefScriptFields function. Simplifies alonzoOnwardsTxOutToJson and documents the per-era field layout in one place.

+        fail "babbageOnwardsTxOutParseJson: inlineDatumhash present without inlineDatumRaw"
+      pure $ maybe L.NoDatum L.DatumHash mDatumHash
+  -- Determine reference script
+  refScript <- fmap L.maybeToStrictMaybe $ forM mRefScript scriptInAnyLangToLedgerScript


Replace cast-based value dispatch with ShelleyBasedEra era dispatch, removing all uses of Data.Typeable.cast. Use failEitherWith for hex/CBOR decode errors, maybe for NoDatum/DatumHash, forM + maybeToStrictMaybe for reference script, and mconcat for the hash mismatch error message. Add multi-asset guard for pre-Mary eras. Move scriptInAnyLangToLedgerScript next to its reverse. Fix test Haddock and add inline note for Dijkstra skip.

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch from 87cfa8a to bc2431f Compare April 20, 2026 13:48

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch from bc2431f to 9734a72 Compare April 27, 2026 20:19

github-actions Bot added Stale and removed Stale labels Jun 12, 2026

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch 2 times, most recently from 4c0be1f to 3467b7f Compare June 16, 2026 13:30

Jimbo4350 marked this pull request as ready for review June 25, 2026 15:07

Jimbo4350 requested review from CarlosLopezDeLara, carbolymer, disassembler, erikd and palas as code owners June 25, 2026 15:07

Copilot AI review requested due to automatic review settings June 25, 2026 15:07

Copilot started reviewing on behalf of Jimbo4350 June 25, 2026 15:08 View session

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch from 3467b7f to 223fb95 Compare June 25, 2026 15:10

Copilot AI reviewed Jun 25, 2026

View reviewed changes

palas approved these changes Jun 26, 2026

View reviewed changes

Comment thread cardano-api/src/Cardano/Api/Experimental/Tx/Internal/BodyContent/New.hs Outdated

Comment thread cardano-api/src/Cardano/Api/Experimental/Tx/Internal/BodyContent/New.hs Outdated

Comment thread cardano-api/src/Cardano/Api/Experimental/Tx/Internal/BodyContent/New.hs Outdated

carbolymer requested changes Jun 26, 2026

View reviewed changes

Jimbo4350 added 2 commits June 26, 2026 17:30

Add changelog fragment for FromJSON TxOut

03260f3

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch from 85485f6 to e7109d8 Compare June 26, 2026 22:01

github-advanced-security AI found potential problems Jun 26, 2026

View reviewed changes

Jimbo4350 force-pushed the issue-926-experimental-fromjson-txout branch from e7109d8 to abf58f2 Compare June 26, 2026 22:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add FromJSON instance for new experimental TxOut#1179

Add FromJSON instance for new experimental TxOut#1179
Jimbo4350 wants to merge 4 commits into
masterfrom
issue-926-experimental-fromjson-txout

Jimbo4350 commented Apr 9, 2026

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

palas left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carbolymer left a comment •

edited

Loading

Uh oh!

carbolymer Jun 26, 2026

Uh oh!

Uh oh!

carbolymer Jun 26, 2026

Uh oh!

carbolymer Jun 26, 2026

Uh oh!

carbolymer Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

Jimbo4350 commented Apr 9, 2026

Context

Changelog

How to trust this PR

Checklist

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

palas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carbolymer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carbolymer Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

carbolymer Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

carbolymer Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

carbolymer Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

carbolymer left a comment •

edited

Loading